<document title="Clipper">
<define name="version" value="0.00">
<define name="date" value="1 January 1900" length=20 align="right">





<literal mode="Text">
=============================================================================
Clipper - A Global Clipboard utility                             Version $$version$$

(c) Thomas Leonard, 1999-2004, Stephen Fryatt, 2004-2020 $$date$$
=============================================================================

</literal>





<chapter title="License" file="License">

<cite>Clipper</cite> is licensed under the EUPL, Version&nbsp;1.2 only (the &ldquo;Licence&rdquo;); you may not use this work except in compliance with the Licence.

You may obtain a copy of the Licence at <link ref="#url http://joinup.ec.europa.eu/software/page/eupl">http://joinup.ec.europa.eu/software/page/eupl</link>

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an &ldquo;<strong>as is</strong>&rdquo; basis, <strong>without warranties or conditions of any kind</strong>, either express or implied.

See the Licence for the specific language governing permissions and limitations under the Licence.

The source for <cite>Clipper</cite> can be found alongside this binary download, at <link ref="#url http://www.stevefryatt.org.uk/software">http://www.stevefryatt.org.uk/software</link>

The necessary libraries and build tools can be found at <link ref="#url http://www.stevefryatt.org.uk/software/build">http://www.stevefryatt.org.uk/software/build</link>

</chapter>




<chapter title="Introduction" file="Intro">

The global clipboard provides a way of transferring data between applications. You select the data in one application and cut or copy it onto the clipboard (usually using <key>Ctrl-X</key> and <key>Ctrl-C</key>). You then move to the other application and paste the data from the clipboard (usually <key>Ctrl-V</key>).

<cite>Clipper</cite> allows you to save the current contents of the global clipboard, either to disc or to another application. You can also drag files from a filer window to <cite>Clipper</cite> to put that file on the clipboard, and type the clipboard contents to the caret.

The <cite>IcnClipBrd</cite> module, which allows you to cut and paste in writeable icons using the global clipboard, is no longer supplied with <cite>Clipper</cite>, but is available from <link ref="http://www.stevefryatt.org.uk/software/clipboard/">http://www.stevefryatt.org.uk/software/clipboard/</link>.

The <cite>Clipper</cite> utility was originally called <cite>Clipboard</cite> and written, along with the <cite>IcnClipBrd</cite> module, by Thomas Leonard. It was converted to 32-bit for use on RISC&nbsp;OS&nbsp;5 by myself (Stephen Fryatt), and was renamed <cite>Clipper</cite> in 2020 to resolve a clash with a legitimately-allocated application name. I would like to thank Thomas for allowing his code to be placed in the Public Domain; any problems encountered using the updated application and module are likely to be my fault and should be reported first to the address below.

</chapter>




<chapter title="Installation" file="Install">

To use <cite>Clipper</cite>, simply run it from a Filer window. If you always want it on the iconbar, it can be included in the list of applications to be run at startup in the <icon>Boot</icon> section of Configure.

</chapter>




<chapter title="Using Clipper" file="Use">

Once <cite>Clipper</cite> is loaded, it will install an icon on the iconbar. Click <mouse>select</mouse> on this icon to open the <window>Save clipboard</window> window. If there is anything on the clipboard then you will be able to drag the icon to a directory or to another application to save the clipboard. You can put a file onto the clipboard by dragging it to this window.

If you toggle the window size then you can see an extra box which indicates what <cite>Clipper</cite> is doing. This may be helpful for programmers trying to work out why their program doesn&rsquo;t work with <cite>Clipper</cite>. Note that the problem may well be <cite>Clipper</cite>&rsquo;s fault!

If there is text on the clipboard, an <mouse>adjust</mouse> click on the iconbar icon will type it at the caret. Only those characters which are considered to be either not control characters or white space will be included in the text; content including newlines and carriage returns might not have the expected effects.

</chapter>




<chapter title="Other information" file="Other">

<cite>Clipper</cite> was written by Thomas Leonard. The 32-bit conversion was done by Stephen Fryatt.

</chapter>




<chapter title="History" file="History">

<subhead title="Version 0.01 (20 October 1996)">

<list>
<li>Main window shows type and owner of clipboard and allows user to put things on the clipboard by dragging to the window.
</list>


<subhead title="Version 0.02 (21 October 1996)">

<list>
<li>Added menu and info window.
<li>User can save clipboard to filer or to another app (lots of fun with <code>Wimp_SendMessage</code>!).
</list>


<subhead title="Version 0.03 (22 October 1996)">

<list>
<li>Wrote most of <cite>IcnClipBrd</cite> including transfer of clipboard via <code>Wimp$Scrap</code> and sending using RAM transfer (but not yet receiving data this way).
</list>


<subhead title="Version 0.04 (23 October 1996)">

<list>
<li>Added support for RAM fetch, but had to remove it because it didn&rsquo;t work with some programs which close all menus when you use RAM transfer!
</list>


<subhead title="Version 0.05 (08 September 1998)">

<list>
<li>Made WimpSlot 36K, as someone said it wouldn't run on their computer with 32K. Changed the window layout to make the Owner box bigger.
<li>Fixed serious bug &ndash; didn&rsquo;t work if &lt;Wimp$Scrap&gt; already existed!
</list>


<subhead title="Version 0.06 (15 September 1998)">

<list>
<li>Made WimpSlot 40K, as someone else still couldn&rsquo;t run it!
<li>Removed Shift from all the <cite>IcnClipBrd</cite> key-combos.
<li>Added protocol status report box, and made it work better with <cite>Zap</cite> (though still not perfect).
</list>


<subhead title="Version 0.07 (17 September 1998)">

<list>
<li>Doesn&rsquo;t bring the window to the front when an error occurs unless the window was already open.
<li>Fixed protocol bug &ndash; window handle and icon handle got corrupted when dragging a file owned by one application to another application.
</list>


<subhead title="Version 0.08 (17 September 1998)">

<list>
<li>Now acks <code>Message_DataLoad</code> when copying from one task to another, since the clipboard owner could decide that the receiver had died and delete the scrap file.
<li>Bugfix: <cite>IcnClipBrd</cite> treated any <code>Claim_Entity</code> message as a claim for the global clipboard.
</list>


<subhead title="Version 0.09 (24 July 1999)">

<list>
<li>Added <key>Ctrl-E</key> and <key>Ctrl-K</key> keys to <cite>IcnClipBrd</cite>; requested by Bob Pollard and Stewy.
</list>


<subhead title="Version 0.10 (04 August 1999)">

<list>
<li>Fixed bug in pasting routines &ndash; top-bit-set chars didn&rsquo;t have a leading zero byte added.
</list>


<subhead title="Version 0.11 (07 July 2004)">

Updated by Stephen Fryatt

<list>
<li>Included 32-bit version of the <cite>IcnClipBrd</cite> module.
</list>


<subhead title="Version 0.12 (05 March 2005)">

Updated by Stephen Fryatt and Kell Gatherer

<list>
<li>Added documentation links to iconbar menu and <window>Program info</window> window.
</list>


<subhead title="Version 0.13 (04 August 2007)">

Updated by Stephen Fryatt

<list>
<li>Included <cite>IcnClipBrd</cite> 0.11.
</list>


<subhead title="Version 0.14 (08 August 2007)">

Updated by Stephen Fryatt

<list>
<li><cite>IcnClipBrd</cite> module removed from <cite>Clipper</cite>, and supplied separately to simplify future updates.
</list>


<subhead title="Version 0.15 (03 September 2014)">

Updated by Stephen Fryatt

<list>
<li>Converted source to generic build system usning Tokenize.
<li>Fixed broken code in URI dispatch, including adding missing error handling routines.
<li>Correctly close Templates file after use.
</list>


<subhead title="Version 0.20 (13 June 2020)">

Second beta release.

<list>
<li>Renamed from <cite>Clipboard</cite> to <cite>Clipper</cite> to avoid an allocation clash.
<li>Licence changed to EUPL, following extensive refactoring of the code, to reflect the significant use of <cite>WimpLib</cite> in the application.
<li>Removed TAL icon from <window>program information</window> window to avoid adding an un-allocated sprite name to Wimp Sprite Pool.
<li>Add support for Interactive Help throughout the application.
<li>Extensive code refactoring, including the use of WimpLib for common tasks.
<li>Fix Data Transfer Protocol implementation, including several missing DataLoadAck messages.
<li>Watch for the application owning the clipboard quitting (ticket&nbsp;#712).
</list>


<subhead title="Version 0.30 (29 August 2020)">

Third beta release.

<list>
<li>Licence updated to EUPL&nbsp;v1.2.
<li><mouse>Adjust</mouse>-clicks on the iconbar icon type the clipboard contents at the caret (ticket&nbsp;#725).
<li>Provide better support for applications which don&rsquo;t respond well to requests for the clipboard contents (tickets&nbsp;#714 and #715).
<li>Use ResConf-style system variables to identify resources.
<li>Fall back to the unknown file icon when the Wimp pool doesn&rsquo;t contain a suitable icon for the clipboard contents (ticket&nbsp;#713).
</list>


<subhead title="Version 0.31 (27 October 2020)">

Update to third beta release.

<list>
<li>Include whitespace characters in typed content (Ticket&nbsp;#726).
<li>Add missing ENDCASE in bounced message handling routine (Ticket&nbsp;#727).
<li>Remove an attempt to type the clipboard contents in the case of a direct save from another owner.
</list>

</chapter>




<literal mode="Text">

Updates and Contacting Me
-------------------------

  If you have any comments about the 32-bit version of Clipper and, or
  would like to report any bugs that you find, you can email me at the
  address below.

  Any updates to the module will be made available on my website, at
  http://www.stevefryatt.org.uk/software/clipboard/

  Stephen Fryatt
  email: info@stevefryatt.org.uk
</literal>

